/*
 * // Bristleback plugin - Copyright (c) 2010 bristleback.googlecode.com
 * // ---------------------------------------------------------------------------
 * // This program is free software; you can redistribute it and/or modify it
 * // under the terms of the GNU Lesser General Public License as published by the
 * // Free Software Foundation; either version 3 of the License, or (at your
 * // option) any later version.
 * // This library is distributed in the hope that it will be useful,
 * // but without any warranty; without even the implied warranty of merchantability
 * // or fitness for a particular purpose.
 * // You should have received a copy of the GNU Lesser General Public License along
 * // with this program; if not, see <http://www.gnu.org/licenses/lgpl.html>.
 * // ---------------------------------------------------------------------------
 */

package pl.bristleback.server.bristle.binding;

import pl.bristleback.server.bristle.binding.resolvers.BindingEngine;

import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.Target;

/**
 * This annotation defines complex object binding operation.
 * Each property must be included in {@link Bind#properties()} to be injected into object.
 * Property getters and setters are required to ensure proper working of binding.
 * Currently, this annotation is processed only in action classes.
 * Implementations of {@link pl.bristleback.server.bristle.binding.BindingsProcessor} are used to process this annotation.
 * Default bindings processor and default binding engine can be changed by setting correspondent property in jwebsocket.xml.
 * <p/>
 * Created on: 2011-01-27 17:54:49 <br/>
 *
 * @author Wojciech Niemiec
 * @see pl.bristleback.server.bristle.config.BristleConfigurationElement#DEFAULT_BINDING_ENGINE Default binding engine
 * @see pl.bristleback.server.bristle.config.BristleConfigurationElement#BINDINGS_PROCESSOR Bindings processor
 */
@Target({ElementType.FIELD})
@Retention(java.lang.annotation.RetentionPolicy.RUNTIME)
public @interface Bind {


  /**
   * Name of the token element that will be used as root by binding engine. For example, with rootName value "root",
   * engine should check whether token contains element with key "root" and use it as main container of processed object values.
   *
   * @return root element name.
   */
  String rootName() default "";

  /**
   * List of included properties.
   *
   * @return List of included properties.
   */
  Property[] properties();

  /**
   * Engine used to process this annotation.
   *
   * @return binding engine used in this annotation.
   * @see pl.bristleback.server.bristle.config.BristleConfigurationElement#DEFAULT_BINDING_ENGINE Default binding engine
   */
  Class<? extends BindingEngine> engine() default BindingEngine.class;
}
